home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 1998 June / Software of the Month Club 1998 June.iso / mac / Business / Hi's Universal Saver / Menu Events 1.3 / Menu Events Help / Menu Events Help.rsrc / STR#_1027.txt < prev    next >
Encoding:
Text File  |  1998-04-13  |  6.9 KB  |  281 lines
  1. 
  2.  
  3. 
  4.  
  5. ‹
  6.  
  7. ‹
  8.  
  9. ├ÑHow Does Menu Events Work?
  10.  
  11. 
  12.  
  13. 
  14.  
  15. When you send a Query Menu List event, the ideal application dispatches
  16.  
  17. the resulting high-level event as an Apple event without looking at it.  The
  18.  
  19. event handler provided by Menu Events forms a reply to the query on the
  20.  
  21. basis of the applicationΓÇÖs menu list structure.  Through all of this, the
  22.  
  23. application stays in the background or in the foreground, wherever it was
  24.  
  25. before.
  26.  
  27. 
  28.  
  29. 
  30.  
  31. When you send a Query Menu or Select Menu Item event, the same things
  32.  
  33. happen, but the event handling is more complex.
  34.  
  35. 
  36.  
  37. First, it verifies that the given menu is valid.  If not, it returns
  38.  
  39. noSuchMenuErr.
  40.  
  41. 
  42.  
  43. Second, it asks for the application to be brought to the front for user
  44.  
  45. interaction, because it could be dangerous to feed the target application a
  46.  
  47. menu bar click while it is in the background, something that never happens
  48.  
  49. in normal operation.  If it is refused, it returns errAENoUserInteraction.
  50.  
  51. 
  52.  
  53. Third, it patches some traps so that it can gain control of menu bar clicks.
  54.  
  55. If it finds that the patches are already in place, meaning that an earlier
  56.  
  57. Menu event is still pending, it returns menuEventPendingErr.
  58.  
  59. 
  60.  
  61. Fourth, if everything is OK, it posts an event to simulate a mouse click in
  62.  
  63. the menu bar, with modifier keys if specified.  The patched traps tell the
  64.  
  65. application that no menu item was selected.  The patches then remove
  66.  
  67. themselves.  This step is solely to ensure that the application brings its
  68.  
  69. menus up to date.
  70.  
  71. 
  72.  
  73. Fifth (in the case of a Select Menu Item event), it verifies that the given
  74.  
  75. menu item is valid and enabled.  If not, it returns noSuchMenuErr,
  76.  
  77. noSuchMenuItemErr, or menuItemDisabledErr.  If the menu has a
  78.  
  79. non-standard menu definition procedure, its way of counting or disabling
  80.  
  81. items may differ from the norm.  Menu Events assumes that the count and
  82.  
  83. enable/disable flags are set in the normal fashion.
  84.  
  85. 
  86.  
  87. Sixth (in the case of a Select Menu Item event), it posts an event to
  88.  
  89. simulate another mouse click in the menu bar, with modifier keys if
  90.  
  91. specified.  The patched traps tell the application that the given item was
  92.  
  93. selected.  The patches then remove themselves.  From there, it is exactly
  94.  
  95. as though the user had actually made the selection.
  96.  
  97. 
  98.  
  99. NOTE:  When replying to any of the three event types, Menu Events
  100.  
  101. includes a null ΓÇ£tattooΓÇ¥ parameter to prove that it handled the event,
  102.  
  103. rather than some handler supplied by the application.  Many Microsoft
  104.  
  105. applications, for example, bind their own handler over all Apple event
  106.  
  107. classes, preventing Menu Events from working.  (The handler wouldnΓÇÖt be
  108.  
  109. a problem if it returned errAEEventNotHandled when faced with an
  110.  
  111. unknown Apple event, as it should.)
  112.  
  113. 
  114.  
  115. 
  116.  
  117. 
  118.  
  119. xUser Interaction Policy
  120.  
  121. 
  122.  
  123. The Apple Event Manager implements a complicated but sensible model for
  124.  
  125. joint sender/receiver control over user interaction.  Menu Events doesnΓÇÖt
  126.  
  127. know which menu selections will really require user interaction, but even
  128.  
  129. if it did, it would still have to request user interaction just to bring the
  130.  
  131. target application to the front, where an application always expects to be
  132.  
  133. when it sees a mouse-down event.
  134.  
  135. 
  136.  
  137. 
  138.  
  139. The sending program must set the kAECanInteract or kAEAlwaysInteract
  140.  
  141. flag in the sendMode parameter to AESend, in order to achieve user
  142.  
  143. interaction.  It should also set the kAECanSwitchLayer flag, allowing the
  144.  
  145. target application to come to the front without having to post a
  146.  
  147. notification request.  If the target application is in the background, and
  148.  
  149. receives a Menu event with this flag not set, it may go into a notification
  150.  
  151. wait state, disrupting its usual background event processing behavior.
  152.  
  153. 
  154.  
  155. If both the sending program and target application are in the background,
  156.  
  157. the kAECanSwitchLayer flag has no effect, and the notification request is
  158.  
  159. posted anyway.  Since your sending program is indirectly instigating a
  160.  
  161. user interaction, it should call AEInteractWithUser before sending the
  162.  
  163. Menu event, if there is any chance that it will be in the background at the
  164.  
  165. time.  Another approach would be to call SetFrontProcess to activate the
  166.  
  167. target application before sending it a Menu event.
  168.  
  169. 
  170.  
  171. If the target application is in that rare user interaction state,
  172.  
  173. kAEInteractWithSelf, where it disallows interaction requested by any
  174.  
  175. other process, the Menu event handler will respect that state, and refuse
  176.  
  177. the event.
  178.  
  179. 
  180.  
  181. If the sending and receiving applications are on different machines, the
  182.  
  183. usual program linking checks apply, namely, Sharing Setup (on/off),
  184.  
  185. Users & Groups (permission to user), and FinderΓÇÖs Sharing (permission to
  186.  
  187. application).
  188.  
  189. 
  190.  
  191. If the Menu Events extension is locked, using FinderΓÇÖs Get Info dialog, then
  192.  
  193. only target applications which explicitly allow interaction with all
  194.  
  195. processes can be controlled by remote senders.  If it is not locked, and if
  196.  
  197. it sees that the user interaction state is kAEInteractWithLocal, which is
  198.  
  199. the default value, it will momentarily change it to kAEInteractWithAll, so
  200.  
  201. that events sent from a remote machine are not rejected.  This trick is
  202.  
  203. necessary for Menu Events to be useful with most target applications,
  204.  
  205. because most will assume the default interaction state, not expecting any
  206.  
  207. remote sender to require user interaction.  The icon displayed by Menu
  208.  
  209. Events at startup shows whether or not the lock is in effect.
  210.  
  211. 
  212.  
  213. IMPORTANT NOTE:  Users of machines where Menu Events is installed
  214.  
  215. should be careful about which users and applications are enabled for
  216.  
  217. remote program linking.  In particular, guest users should not be allowed
  218.  
  219. to do program linking unless Menu Events is locked.
  220.  
  221. 
  222.  
  223. 
  224.  
  225. 
  226.  
  227. xApple Event Recording Capability
  228.  
  229. 
  230.  
  231. When you are using a high-level-event-aware application on a machine
  232.  
  233. where Menu Events is installed, menu item selection behavior is modified
  234.  
  235. if the Caps Lock key is down at the time you release the mouse button.
  236.  
  237. Menu Events will create a Select Menu Item Apple event to represent the
  238.  
  239. selection (including parameters for any modifier keys which were
  240.  
  241. pressed), so that a script editor can record the event as a script
  242.  
  243. command.  A gentle ΓÇ£twangΓÇ¥ sound confirms that this has happened.
  244.  
  245. Whether or not it succeeds in recording the event, the menu selection will
  246.  
  247. be processed in the usual way.
  248.  
  249. 
  250.  
  251. 
  252.  
  253. If the application is scriptable in its own right, a script editor may record
  254.  
  255. two commands when you select an item from its menus.  To prevent this
  256.  
  257. duplication, you can use the itemΓÇÖs Command-key equivalent (if any), or
  258.  
  259. release the Caps Lock key, to suppress the recording capability.
  260.  
  261. 
  262.  
  263. If an application seems to be misinterpreting or not receiving menu
  264.  
  265. selections, try again with the Caps Lock key up.  The command will not be
  266.  
  267. recorded, but should work as usual.
  268.  
  269. 
  270.  
  271. NOTE:  While receiving a Select Menu Item event does simulate a menu
  272.  
  273. selection, it does not cause a Select Menu Item script command to be
  274.  
  275. recorded.
  276.  
  277. 
  278.  
  279. 
  280.  
  281.